home *** CD-ROM | disk | FTP | other *** search
/ Power Programmierung 2 / Power-Programmierung CD 2 (Tewi)(1994).iso / c / library / dos / window / tegl / tutor / menus.txt < prev    next >
Encoding:
Text File  |  1991-08-27  |  10.7 KB  |  395 lines
  1. MENUS
  2. -------------------------------------------------------------------
  3.  
  4. The TEGL WINDOWS TOOLKIT II provides an extensive number of menu
  5. functions. You can create bar menus and pull-down (or up) menus.
  6. The basic item in a TEGL menu is the Option Menu. These are accessed
  7. through a pointer, an optionmptr.
  8.  
  9. Creating a bar menu require a few steps. First we have to create
  10. some option menus to attach to the bar menu. To do this use the function
  11. createoptionmenu. It is declared as follows:
  12.  
  13. optionmptr createoptionmenu(fontptr fonttype);
  14.  
  15. fonttype is the font to use when displaying the menu selections. The
  16. optionmptr that is returned is used to add selections to the option
  17. menu and is finally attached to a bar menu (or mouse click area).
  18.  
  19. After the option menu has been created use defineoptions to add selections
  20. to the menu.
  21.  
  22. void defineoptions(optionmptr om, char *entrystr, unsigned char active,
  23.                      callproc event);
  24.  
  25. The first parameter, om, is the optionmptr that must have been created
  26. with defineoptions. entrystr is the text that will be displayed for the
  27. menu selection. Active sets whether the menu item can be selected, if
  28. TRUE then it can be selected, when FALSE it cannot and will appear in
  29. a lighter shade than the other menu selections. Event is the event-handler
  30. that will be called when the menu selection is clicked on.
  31.  
  32. The '-' (hyphen) is used to place a separator line between options, it will
  33. appear as continuous line. When adding a separator the active parameter
  34. should alway be FALSE and the event should be nilunitproc which is a
  35. place holder event-handler that just returns.
  36.  
  37. Note that menu selections (either bar or option menu) can have the tilde
  38. character '~' placed around one of the characters in the text for the menu
  39. selection. When this item is displayed the character will be underscored
  40. and the corresponding key will be trapped for.
  41.  
  42. The next step is create a bar menu that the option menu('s) can be attached
  43. to. To do this we use createbarmenu.
  44.  
  45. void createbarmenu(unsigned x, unsigned y, unsigned length);
  46.  
  47. x, y is the postion (in absolute screen coordinates) where the bar menu is
  48. to be placed. length is the length of the menu in pixels.
  49.  
  50. The font that is used to display the bar menu is the current font, if you
  51. want to use a specific font use setteglfont before calling createbarmenu.
  52.  
  53. Hint: A bar menu is really just a long narrow frame, and like any frame
  54. you change certain characteristics. Sometimes it might be useful to save
  55. the stackptr right after creating a bar menu.
  56.  
  57. When the bar menu has been created the option menus are attaced to it using
  58. outbaroption.
  59.  
  60. void outbaroption(char *entrystr, optionmptr om);
  61.  
  62. The entrystr is the bar menu selection and om is the option menu that will
  63. appear when the selection is made. The option menu will appear as a drop
  64. down or drop up menu depending on where the bar menu is located.
  65.  
  66. Here is a small but complete program example of a bar menu with just
  67. one selection. The one selection is an option menu with the entries:
  68. 'File' which does nothing, '-' which gives a separator line (for
  69. appearance sake, and 'Exit' which will end the program.
  70.  
  71. Note: nilunitproc is an event-handler which does nothing. It can be used
  72. as place holder when you are creating the menu interface of program but
  73. haven't completed the guts, and it is also used where an event parameter
  74. (even one that is never called) is required.
  75.  
  76. BEGINFILE> menu1.c
  77.   /* -- menu1.c */
  78.  
  79. #include "teglsys.h"
  80.  
  81. unsigned exitoption(imagestkptr  ifs, msclickptr   ms)
  82.   {
  83.     abortexit("");
  84.     return 0;
  85.   }
  86.  
  87. optionmptr   omfile;
  88.  
  89.  
  90. void main(void)
  91. {
  92.  
  93.  
  94.   easytegl();
  95.   easyout();
  96.  
  97.   omfile = createoptionmenu(f8x12bol);
  98.   defineoptions(omfile," ~O~pen ",TRUE,nilunitproc);
  99.   defineoptions(omfile,"-",TRUE,nilunitproc);
  100.   defineoptions(omfile," E~x~it ",TRUE,exitoption);
  101.   setteglfont(f8x12bol);
  102.   createbarmenu(0,0,getmaxx());
  103.   outbaroption(" ~F~ile ",omfile);
  104.  
  105.   teglsupervisor();
  106. }
  107.  
  108.  
  109.  
  110. ENDFILE>
  111.  
  112. We can nest menus arbitrarily deep. To do this we use
  113.  
  114. void defineoptionssub(optionmptr om, char *entrystr, char active,
  115.                       optionmptr om2);
  116.  
  117. This simply attaches an option menu selection that is another option
  118. menu as opposed to an event-handler. As you can see the last parameter
  119. is an optionmptr.
  120.  
  121. This example adds two levels of menus, they don't do anything (that's
  122. up to you) but it illustrates the use.
  123.  
  124. BEGINFILE> menu2.c
  125.   /* -- menu2.c */
  126.  
  127. #include "teglsys.h"
  128.  
  129.  
  130. unsigned exitoption(imagestkptr  ifs, msclickptr   ms)
  131.   {
  132.     abortexit("");
  133.     return 0;
  134.   }
  135.  
  136.  
  137.      fontptr      menufont;   /* -- by setting the font into a pointer we can  */
  138.                /* -- more easily change our selection of the font */
  139.                /* -- to use.  */
  140.      optionmptr   omfile;
  141.      optionmptr   omfile2;
  142.      optionmptr   omfile3;
  143.  
  144.  
  145. void main(void)
  146. {
  147.  
  148.  
  149.   easytegl();
  150.   easyout();
  151.  
  152.   menufont = f8x12bol;
  153.  
  154.   omfile3 = createoptionmenu(menufont);
  155.     defineoptions(omfile3," ~T~o floppy ",TRUE,nilunitproc);
  156.     defineoptions(omfile3," ~F~rom floppy ",TRUE,nilunitproc);
  157.  
  158.   omfile2 = createoptionmenu(menufont);
  159.     defineoptions(omfile2," ~F~ormat ",FALSE,nilunitproc);
  160.     defineoptions(omfile2," ~D~elete ",FALSE,nilunitproc);
  161.     defineoptionssub(omfile2," ~C~opy ",TRUE,omfile3);
  162.  
  163.   omfile = createoptionmenu(menufont);
  164.   defineoptions(omfile," ~O~pen ",TRUE,nilunitproc);
  165.   defineoptionssub(omfile," ~D~os functions ",TRUE,omfile2);
  166.   defineoptions(omfile,"-",FALSE,nilunitproc);
  167.   defineoptions(omfile," E~x~it ",TRUE,exitoption);
  168.  
  169.   setteglfont(menufont);
  170.   createbarmenu(0,0,getmaxx());
  171.   outbaroption(" ~F~ile ",omfile);
  172.  
  173.   teglsupervisor();
  174. }
  175.  
  176.  
  177.  
  178. ENDFILE>
  179.  
  180.  
  181. Some people really get carried away when it comes to making menus,
  182. generally we don't recommend really long menus and try to keep them
  183. under several hundred items.
  184.  
  185. This example just shows what happens when an excessive number of menu
  186. selections is added to an option menu.
  187.  
  188. BEGINFILE> menu3.c
  189.   /* -- menu3.c  */
  190.  
  191. #include "teglsys.h"
  192.  
  193. char *itos(int i)
  194.   {
  195.     static char         s[25];
  196.  
  197.     itoa(i,s,10);
  198.     return s;
  199.   }
  200.  
  201.  
  202. unsigned exitoption( imagestkptr ifs, msclickptr ms)
  203.   {
  204.     abortexit("");
  205.     return 0;
  206.   }
  207.  
  208. optionmptr   omfile;
  209.      optionmptr   omopen;
  210.      int      i;
  211.  
  212. void main(void)
  213. {
  214.  
  215.   char  fn[20];
  216.   easytegl();
  217.   easyout();
  218.  
  219.   omopen = createoptionmenu(f8x8bold);
  220.     for (i = 1; i <= 50; i++) {
  221.       strcpy(fn," file ");
  222.       strcat(fn,itos(i));
  223.       defineoptions(omopen,fn,random(2) == 1,nilunitproc);
  224.       }
  225.  
  226.   omfile = createoptionmenu(f8x12bol);
  227.   defineoptionssub(omfile," ~O~pen ",TRUE,omopen);
  228.   defineoptions(omfile,"-",FALSE,nilunitproc);
  229.   defineoptions(omfile," E~x~it ",TRUE,exitoption);
  230.   setteglfont(&f8x12bol);
  231.   createbarmenu(0,0,getmaxx());
  232.   outbaroption(" ~F~ile ",omfile);
  233.  
  234.   teglsupervisor();
  235. }
  236.  
  237.  
  238.  
  239. ENDFILE>
  240.  
  241. A useful item to have in a menu is a check-marked item. These are usually
  242. boolean flags to indicate some sort of preference. There is a special
  243. option menu item for this:
  244.  
  245. void defineoptionscheck(optionmptr om, char *entrystr, unsigned char active,
  246.                          callproc event, char *chkmark);
  247.  
  248. The big distinction here is that we pass a variable to the routine so
  249. that when it is selected the variable will be toggled. After the variable
  250. is updated then the event-handler is called, presumably to do some
  251. processing if required. Our example doesn't do this, but you probably
  252. get the idea.
  253.  
  254. When the item is TRUE then a check mark is displayed next to it, when
  255. FALSE no check mark.
  256.  
  257.  
  258. BEGINFILE> menu4.c
  259.   /* -- menu4.c */
  260.  
  261. #include "teglsys.h"
  262.  
  263. unsigned exitoption(imagestkptr  ifs, msclickptr   ms)
  264.   {
  265.     abortexit("");
  266.     return 0;
  267.   }
  268.  
  269.  
  270.      fontptr      menufont;
  271.      optionmptr   omfile;
  272.  
  273.  
  274.     char  fullpath      = TRUE;
  275.  
  276.  
  277. void main(void)
  278. {
  279.  
  280.  
  281.   easytegl();
  282.   easyout();
  283.  
  284.   menufont = f8x12bol;
  285.  
  286.  
  287.  
  288.   omfile = createoptionmenu(menufont);
  289.   defineoptions(omfile," ~O~pen ",TRUE,nilunitproc);
  290.   defineoptionscheck(omfile," ~F~ull path ",TRUE,nilunitproc,&fullpath);
  291.   defineoptions(omfile,"-",FALSE,nilunitproc);
  292.   defineoptions(omfile," E~x~it ",TRUE,exitoption);
  293.  
  294.   setteglfont(menufont);
  295.   createbarmenu(0,0,getmaxx());
  296.   outbaroption(" ~F~ile ",omfile);
  297.  
  298.   teglsupervisor();
  299. }
  300.  
  301.  
  302.  
  303. ENDFILE>
  304.  
  305. Another useful kind of check mark is one where there can be a limited
  306. number of choices but more than just a boolean toggle.
  307.  
  308. void defineoptionsradio(optionmptr om, char *entrystr, char active,
  309.                 callproc event, unsigned entryradiovalue, unsigned *radiovar);
  310.  
  311.  
  312.  
  313. Here the distinction is radiovar is an  unsigned, so you could have
  314. a lot of choices but generally this kind of item is used for 2 to 5 or
  315. perhaps a few more. Each item that uses the same radiovar must have
  316. a different entryradiovalue. As with defineoptionscheck the event-handler
  317. is called after the variable has been updated.
  318.  
  319. BEGINFILE> menu5.c
  320.   /* -- menu5.c  */
  321.  
  322. #include "teglsys.h"
  323.  
  324. unsigned exitoption(imagestkptr  ifs, msclickptr   ms)
  325.   {
  326.     abortexit("");
  327.     return 0;
  328.   }
  329.  
  330.  
  331.      fontptr      menufont;
  332.      optionmptr   omfile;
  333.  
  334.      unsigned         sortoption    = 1;
  335.  
  336.  
  337. void main(void)
  338. {
  339.  
  340.  
  341.   easytegl();
  342.   easyout();
  343.  
  344.   menufont = f8x12bol;
  345.  
  346.  
  347.   omfile = createoptionmenu(menufont);
  348.   defineoptions(omfile," ~O~pen ",TRUE,nilunitproc);
  349.   defineoptions(omfile,"-",FALSE,nilunitproc);
  350.   defineoptionsradio(omfile," ~N~ame ",TRUE,nilunitproc,1,&sortoption);
  351.   defineoptionsradio(omfile," ~E~xtension ",TRUE,nilunitproc,2,&sortoption);
  352.   defineoptionsradio(omfile," ~D~ate ",TRUE,nilunitproc,3,&sortoption);
  353.   defineoptionsradio(omfile," N~o~ne ",TRUE,nilunitproc,4,&sortoption);
  354.   defineoptions(omfile,"-",FALSE,nilunitproc);
  355.   defineoptions(omfile," E~x~it ",TRUE,exitoption);
  356.  
  357.   setteglfont(menufont);
  358.   createbarmenu(0,0,getmaxx());
  359.   outbaroption(" ~F~ile ",omfile);
  360.  
  361.   teglsupervisor();
  362. }
  363.  
  364.  
  365.  
  366. ENDFILE>
  367.  
  368.  
  369. PREFERENCES
  370.  
  371. You can set a number of items to suit your needs or preferences
  372. for menus.
  373.  
  374. void sethidesubmenu(char onoff);
  375.  
  376. This sets whether the sub menus should be dropped before the resulting
  377. event-handler has returned. The default is for the sub menus to remain
  378. visible on the screen (FALSE). If set TRUE then the menus are hidden just
  379. as soon as a selection is made.
  380.  
  381. setomdisplaynum(optionmptr om, unsigned num);
  382.  
  383. This sets the limit on how many menu items to display before an
  384. option menu sprouts a slider bar. If you don't change it then the
  385. menu can be the full size of the screen.
  386.  
  387.  
  388.  
  389.  
  390.  
  391. See the example program 'menudemo.pas' for a comprehensive look at
  392. how a menu system can be set up.
  393.  
  394. ------- END MENUS.TXT
  395.